.TH astyle 1 "2023-09-21" "Andre Simon" "user documentation"

.SH NAME
astyle - C syntax indenter and formatter

.SH SYNOPSIS
.B astyle
[OPTIONS] [input files]

.SH DESCRIPTION
.B astyle
provides a variety of options to apply a consistent coding style to C, C++, Java or Objective-C source code files.
.PP
When indenting a specific file, the resulting indented file RETAINS
the original file-name. The original pre-indented file is renamed,
with a suffix of '.orig' added to the original filename.
.PP
Wildcards (* and ?) may be used in the filename.
A 'recursive' option can process directories recursively.
Multiple file extensions may be separated by a comma.
.PP
By default, astyle is set up to indent with four spaces per indent,
a maximal indentation of 40 spaces inside continuous statements,
a minimum indentation of eight spaces inside conditional statements,
and NO formatting options.


.SH Brace Style Options

If no brace style is requested, the opening braces will not be
changed and closing braces will be broken from the preceding line.

.IP "--style=allman OR --style=bsd OR --style=break OR -A1"
Allman style formatting/indenting.
Broken braces.

.IP "--style=java OR --style=attach OR -A2"
Java style formatting/indenting.
Attached braces.

.IP "--style=kr OR --style=k&r OR --style=k/r OR -A3"
Kernighan & Ritchie style formatting/indenting.
Linux braces.

.IP "--style=stroustrup OR -A4"
Stroustrup style formatting/indenting.
Linux braces, with broken closing headers.

.IP "--style=whitesmith OR -A5"
Whitesmith style formatting/indenting.
Broken, indented braces.
Indented class blocks and switch blocks.

.IP "--style=vtk OR -A15"
VTK style formatting/indenting.
Broken, indented braces except for the opening braces.

.IP "--style=ratliff OR --style=banner OR -A6"
Ratliff style formatting/indenting.
Attached, indented braces.

.IP "--style=gnu OR -A7"
GNU style formatting/indenting.
Broken braces, indented blocks.

.IP "--style=linux OR --style=knf OR -A8"
Linux style formatting/indenting.
Linux braces, minimum conditional indent is one-half indent.

.IP "--style=horstmann OR --style=run-in OR -A9"
Horstmann style formatting/indenting.
Run-in braces, indented switches.

.IP "--style=1tbs OR --style=otbs OR -A10"
One True Brace Style formatting/indenting.
Linux braces, add braces to all conditionals.

.IP "--style=google OR -A14"
Google style formatting/indenting.
Attached braces, indented class modifiers.

.IP "--style=mozilla OR -A16"
Mozilla style formatting/indenting.
Linux braces, with broken braces for structs and enums,
and attached braces for namespaces.

.IP "--style=webkit OR -A17"
WebKit style formatting/indenting.
Linux braces, with attached closing headers.

.IP "--style=pico OR -A11"
Pico style formatting/indenting.
Run-in opening braces and attached closing braces.
Uses keep one line blocks and keep one line statements.

.IP "--style=lisp OR -A12"
Lisp style formatting/indenting.
Attached opening braces and attached closing braces.
Uses keep one line statements.

.SH  Tab Options:

If no indentation option is set, the default
option of 4 spaces per indent will be used.

.IP "--indent=spaces=# OR -s#"
Indent using # spaces per indent. Not specifying #
will result in a default of 4 spaces per indent.

.IP "--indent=tab OR --indent=tab=# OR -t OR -t#"
Indent using tab characters, assuming that each
indent is # spaces long. Not specifying # will result
in a default assumption of 4 spaces per indent.

.IP "--indent=force-tab=# OR -T#"
Indent using tab characters, assuming that each
indent is # spaces long. Force tabs to be used in areas
AStyle would prefer to use spaces.

.IP "--indent=force-tab-x=# OR -xT#"
Allows the tab length to be set to a length that is different
from the indent length. This may cause the indentation to be
a mix of both spaces and tabs. This option sets the tab length.

.SH  Brace Modify Options:

.IP "--attach-namespaces OR -xn"
Attach braces to a namespace statement.

.IP "--attach-classes OR -xc"
Attach braces to a class statement.

.IP "--attach-inlines OR -xl"
Attach braces to class inline function definitions.

.IP "--attach-extern-c OR -xk"
Attach braces to an extern "C" statement.

.IP "--attach-closing-while OR -xV"
Attach closing while of do-while to the closing brace.

.SH  Indentation Options:

.IP "--indent-classes OR -C"
Indent 'class' blocks so that the entire block is indented.

.IP "--indent-modifiers OR -xG"
Indent 'class' access modifiers, 'public:', 'protected:' or
'private:', one half indent. The rest of the class is not
indented.

.IP "--indent-switches OR -S"
Indent 'switch' blocks, so that the inner 'case XXX:'
headers are indented in relation to the switch block.

.IP "--indent-cases OR -K"
Indent case blocks from the 'case XXX:' headers.
Case statements not enclosed in blocks are NOT indented.

.IP "--indent-namespaces OR -N"
Indent the contents of namespace blocks.

.IP "--indent-after-parens OR -xU"
Indent, instead of align, continuation lines following lines
that contain an opening paren '(' or an assignment '='.

.IP "--indent-continuation=# OR -xt#"
Indent continuation lines an additional # indents.
The valid values are 0 thru 4 indents.
The default value is 1 indent.

.IP "--indent-labels OR -L"
Indent labels so that they appear one indent less than
the current indentation level, rather than being
flushed completely to the left (which is the default).

.IP "--indent-preproc-block OR -xW"
Indent preprocessor blocks at brace level 0.
Without this option the preprocessor block is not indented.

.IP "--indent-preproc-cond OR -xw"
Indent preprocessor conditional statements #if/#else/#endif
to the same level as the source code.

.IP "--indent-preproc-define OR -w"
Indent multi-line preprocessor #define statements.

.IP "--indent-col1-comments OR -Y"
Indent line comments that start in column one.

.IP "--min-conditional-indent=# OR -m#"
Indent a minimal # spaces in a continuous conditional
belonging to a conditional header.
The valid values are:
0 - no minimal indent.
1 - indent at least one additional indent.
2 - indent at least two additional indents.
3 - indent at least one-half an additional indent.
The default value is 2, two additional indents.

.IP "--max-continuation-indent=# OR -M#"
Indent a maximal # spaces in a continuation line,
relative to the previous line.
The minimum and default value is 40.

.SH   Padding Options

.IP "--break-blocks OR -f"
Insert empty lines around unrelated blocks, labels, classes, ...

.IP "--break-blocks=all OR -F"
Like --break-blocks, except also insert empty lines
around closing headers (e.g. 'else', 'catch', ...).

.IP "--pad-oper OR -p"
Insert space padding around operators.

.IP "--pad-comma OR -xg"
Insert space padding after commas.

.IP "--pad-paren OR -P"
Insert space padding around parenthesis on both the outside
and the inside.

.IP "--pad-paren-out OR -d"
Insert space padding around parenthesis on the outside only.

.IP "--pad-first-paren-out OR -xd"
Insert space padding around first parenthesis in a series on
the outside only.

.IP "--pad-paren-in OR -D"
Insert space padding around parenthesis on the inside only.

.IP "--pad-header OR -H"
Insert space padding after paren headers (e.g. 'if', 'for'...).

.IP "--unpad-paren OR -U"
Remove unnecessary space padding around parenthesis. This
can be used in combination with the 'pad' options above.

.IP "--pad-empty-paren OR -xo"
Apply padding to empty pairs of parentheses; combine with other
parenthesis padding options.

.IP "--pad-brackets"
Insert space padding around square brackets on both the outside
and the inside (experimental).

.IP "--unpad-brackets"
Remove unnecessary space padding around square brackets (experimental).

.IP "--delete-empty-lines OR -xe"
Delete empty lines within a function or method.
It will NOT delete lines added by the break-blocks options.

.IP "--fill-empty-lines OR -E"
Fill empty lines with the white space of their
previous lines.

.IP "--align-pointer=type   OR -k1"
.IP "--align-pointer=middle OR -k2"
.IP "--align-pointer=name   OR -k3"
Attach a pointer or reference operator (*, &, or ^) to either
the operator type (left), middle, or operator name (right).
To align the reference separately use --align-reference.

.IP "--align-reference=none   OR -W0"
.IP "--align-reference=type   OR -W1"
.IP "--align-reference=middle OR -W2"
.IP "--align-reference=name   OR -W3"
Attach a reference operator (&) to either
the operator type (left), middle, or operator name (right).
If not set, follow pointer alignment.

.IP "--squeeze-lines=#"
Remove superfluous empty lines exceeding the given number (experimental).

.IP "--squeeze-ws"
Remove superfluous whitespace (experimental).

.SH  Formatting Options

.IP "--break-closing-braces OR -y"
Break braces before closing headers (e.g. 'else', 'catch', ...).
Use with --style=java, --style=kr, --style=stroustrup, --style=linux, or --style=1tbs."

.IP "--break-elseifs OR -e"
Break 'else if()' statements into two different lines.

.IP "--break-one-line-headers OR -xb"
Break one line headers (e.g. 'if', 'while', 'else', ...) from a
statement residing on the same line.

.IP "--add-braces OR -j"
Add braces to unbraced one line conditional statements.

.IP "--add-one-line-braces OR -J"
Add one line braces to unbraced one line conditional
statements.

.IP "--remove-braces OR -xj"
Remove braces from a braced one line conditional statements.

.IP "--break-return-type      OR -xB"
.IP "--break-return-type-decl OR -xD"
Break the return type from the function name. Options are
for the function definitions and the function declarations.

.IP "--attach-return-type      OR -xf"
.IP "--attach-return-type-decl OR -xh"
Attach the return type to the function name. Options are
for the function definitions and the function declarations.

.IP "--keep-one-line-blocks OR -O"
Don't break blocks residing completely on one line.

.IP "--keep-one-line-statements OR -o"
Don't break lines containing multiple statements into
multiple single-statement lines.

.IP "--convert-tabs OR -c"
Convert tabs to the appropriate number of spaces.

.IP "--close-templates OR -xy"
Close ending angle brackets on template definitions.

.IP "--remove-comment-prefix OR -xp"
Remove the leading '*' prefix on multi-line comments and
indent the comment text one indent.

.IP "--max-code-length=#   OR -xC#"
.IP "--break-after-logical OR -xL"
max-code-length=# will break the line if it exceeds more than
# characters. The valid values are 50 thru 200.
If the line contains logical conditionals they will be placed
first on the new line. The option break-after-logical will
cause the logical conditional to be placed last on the
previous line.

.IP "--mode=c"
Indent a C or C++ source file (this is the default).

.IP "--mode=java"
Indent a Java source file.

.IP "--mode=cs"
Indent a C# source file.

.IP "--mode=objc"
Indent an Objective-C source file.

.IP "--mode=js"
Indent a JavaScript source file (experimental).

.SH  Objective-C Options

.IP "--pad-method-prefix OR -xQ"
Insert space padding after the '-' or '+' Objective-C
method prefix.

.IP "--unpad-method-prefix OR -xR"
Remove all space padding after the '-' or '+' Objective-C
method prefix.

.IP "--pad-return-type OR -xq"
Insert space padding after the Objective-C return type.

.IP "--unpad-return-type OR -xr"
Remove all space padding after the Objective-C return type.

.IP "--pad-param-type OR -xS"
Insert space padding after the Objective-C param type.

.IP "--unpad-param-type OR -xs"
Remove all space padding after the Objective-C param type.

.IP "--align-method-colon OR -xM"
Align the colons in an Objective-C method definition.

.IP "--pad-method-colon=none   OR -xP"
.IP "--pad-method-colon=all    OR -xP1"
.IP "--pad-method-colon=after  OR -xP2"
.IP "--pad-method-colon=before OR -xP3"
Add or remove space padding before or after the colons in an
Objective-C method call.

.SH  Other Options

.IP "--suffix=####"
Append the suffix #### instead of '.orig' to original filename.

.IP "--suffix=none OR -n"
Do not retain a backup of the original file.

.IP "--recursive OR -r OR -R"
Process subdirectories recursively.

.IP "--dry-run"
Perform a trial run with no changes made to check for formatting.

.IP "--exclude=####"
Specify a file or directory #### to be excluded from processing.

.IP "--ignore-exclude-errors OR -i"
Allow processing to continue if there are errors in the exclude=####
options. It will display the unmatched excludes.

.IP "--ignore-exclude-errors-x OR -xi"
Allow processing to continue if there are errors in the exclude=####
options. It will NOT display the unmatched excludes.

.IP "--errors-to-stdout OR -X"
Print errors and help information to standard-output rather than
to standard-error.

.IP "--preserve-date OR -Z"
Preserve the original file's date and time modified. The time
modified will be changed a few micro seconds to force a compile.

.IP "--verbose OR -v"
Verbose mode. Extra informational messages will be displayed.

.IP "--formatted OR -Q"
Formatted display mode. Display only the files that have been
formatted.

.IP "--quiet OR -q"
Quiet mode. Suppress all output except error messages.

.IP "--lineend=windows OR -z1"
.IP "--lineend=linux   OR -z2"
.IP "--lineend=macold  OR -z3"
Force use of the specified line end style. Valid options
are windows (CRLF), linux (LF), and macold (CR).

.SH  Command Line Only

.IP "--options=####"
.IP "--options=none"
Specify a default option file #### to read and use.
It must contain a file path and a file name.
'none' disables the default option file.

.IP "--project"
.IP "--project=####"
.IP "--project=none"
Specify a project option file #### to read and use.
It must contain a file name only, without a directory path.
The file should be included in the project top-level directory.
The default file name is .astylerc or _astylerc.
'none' disables the project or environment variable file.

.IP "--ascii OR -I"
The displayed output will be ascii characters only.

.IP "--version OR -V"
Print version number.

.IP "--help OR -h OR -?"
Print this help message.

.IP "--html OR -!"
Open the HTML help file "astyle.html" in the default browser.
The documentation must be installed in the standard install path.

.IP "--html=####"
Open a HTML help file in the default browser using the file path
####. The path may include a directory path and a file name, or a
file name only. Paths containing spaces must be enclosed in quotes.

.IP "--stdin=####"
Use the file path #### as input to single file formatting.
This is a replacement for redirection.

.IP "--stdout=####"
Use the file path #### as output from single file formatting.
This is a replacement for redirection.


.SH  Option Files

Artistic Style looks for a default option file and/or a project
option file in the following order:
.PP
1. The command line options have precedence.
.PP
2. The project option file has precedence over the default file
    o the file name indicated by the --project= command line option.
    o the file named .astylerc or _ astylerc.
    o the file name identified by ARTISTIC_STYLE_PROJECT_OPTIONS.
    o the file is disabled by --project=none on the command line.
.PP
3. The default option file that can be used for all projects.
    o the file path indicated by the --options= command line option.
    o the file path indicated by ARTISTIC_STYLE_OPTIONS.
    o the file named .astylerc in the HOME directory (for Linux).
    o the file name astylerc in the APPDATA directory (for Windows).
    o the file is disabled by --project=none on the command line.
.PP
Long options within the option files may be written without '--'.
.PP
Line-end comments begin with a '#'.

.SH Disable Formatting

Blocks of code can be disabled with the comment tags *INDENT-OFF*
and *INDENT-ON*. It must be contained in a one-line comment.
.PP
Padding of operators can be disabled on a single line using the
comment tag *NOPAD*. It must be contained in a line-end comment.


.SH Examples
File conversions:
.PP
astyle  --style=allman  /home/project/foo.cpp
.PP
astyle  --style=allman  --recursive  /home/project/*.cpp,*.h
.PP
astyle --style=allman < OriginalSourceFile > BeautifiedSourceFile

.SH AUTHORS
Andre Simon <as@andre-simon.de>
.SH SEE ALSO
More information at https://sourceforge.net/p/astyle/.
